 /*******************************************************************************
  * Copyright (c) 2006 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  ******************************************************************************/

 package org.eclipse.ui.navigator;

 import org.eclipse.jface.util.LocalSelectionTransfer;
 import org.eclipse.jface.viewers.IStructuredSelection;
 import org.eclipse.swt.dnd.DragSourceEvent;
 import org.eclipse.swt.dnd.Transfer;
 import org.eclipse.swt.dnd.TransferData;
 import org.eclipse.swt.widgets.Event;
 import org.eclipse.swt.widgets.Shell;
 import org.eclipse.ui.PlatformUI;
 import org.eclipse.ui.internal.navigator.NavigatorContentService;
 import org.eclipse.ui.part.PluginTransfer;

 /**
  * Assist the {@link CommonDragAdapter} by providing new TransferTypes and the
  * logic to handle setting up the transfer data. Clients must extend this class
  * as part of the <b>org.eclipse.ui.navigator.viewer/dragAssistant</b>
  * extension. By default, the Common Navigator supports
  * {@link LocalSelectionTransfer} and {@link PluginTransfer}.
  *
  * <p>
  * Clients may extend this class.
  * </p>
  *
  * @see INavigatorDnDService
  * @see CommonDragAdapter
  * @see CommonDropAdapter
  * @see CommonDropAdapterAssistant
  * @see CommonViewer
  * @see <a
  * HREF="http://www.eclipse.org/articles/Article-SWT-DND/DND-in-SWT.html">Drag
  * and Drop: Adding Drag and Drop to an SWT Application</a>
  * @see <a
  * HREF="http://www.eclipse.org/articles/Article-Workbench-DND/drag_drop.html">Drag
  * and Drop in the Eclipse UI (Custom Transfer Types)</a>
  *
  * @since 3.2
  *
  */
 public abstract class CommonDragAdapterAssistant {

     private INavigatorContentService contentService;

     /**
      * Extra TransferTypes allow the Navigator to generate different kinds of
      * payloads for DND clients. By default, the {@link CommonDragAdapter}
      * supports {@link LocalSelectionTransfer} and {@link PluginTransfer}.
      *
      * <p>
      * CommonDragAdapterAssistants can extend the available TransferTypes that a
      * Common Navigator Viewer can generate. Clients should return the set of
      * Transfer Types they support. When a drop event occurs, the available drag
      * assistants will be searched for a <i>enabled</i> assistants for the
      * {@link DragSourceEvent}. Only if the drop event occurs will
      * {@link #setDragData(DragSourceEvent, IStructuredSelection)} be called. If
      * the drop event is cancelled,
      * {@link #setDragData(DragSourceEvent, IStructuredSelection)} will not be
      * called.
      * </p>
      *
      * @return The added transfer types. (e.g. FileTransfer.getInstance()).
      */
     public abstract Transfer[] getSupportedTransferTypes();

     /**
      * Set the value of the {@link org.eclipse.swt.widgets.Event#data} field using the given selection.
      * Clients will only have an opportunity to set the drag data if they have
      * returned a matching Transfer Type from
      * {@link #getSupportedTransferTypes()} for the
      * {@link DragSourceEvent#dataType}.
      * <p>
      * Clients will only have an opportunity to set the data when the drop event
      * occurs. If the drop operation is cancelled, then this method will not be
      * called.
      * </p>
      *
      * @param anEvent
      * The event object should have its {@link Event#data} field set
      * to a value that matches a supported {@link TransferData} type.
      * @param aSelection
      * The current selection from the viewer.
      * @return True if the data could be set; false otherwise.
      */
     public abstract boolean setDragData(DragSourceEvent anEvent,
             IStructuredSelection aSelection);

     /**
      * Accept and remember the content service this assistant is associated
      * with.
      *
      * @param aContentService
      */
     public final void setContentService(INavigatorContentService aContentService) {
         contentService = aContentService;
     }

     /**
      *
      * @return The associated content service.
      */
     public INavigatorContentService getContentService() {
         return contentService;
     }

     /**
      *
      * @return The shell for the viewer this assistant is associated with or the
      * shell of the active workbench window.
      */
     public final Shell getShell() {
         if (contentService != null) {
             ((NavigatorContentService) contentService).getShell();
         }
         return PlatformUI.getWorkbench().getActiveWorkbenchWindow().getShell();
     }

 }

